Crate redis_async
source ·Expand description
A client for Redis using Tokio and Futures.
Three interfaces are provided: one low-level, that makes no assumptions about how Redis is used; a high-level client, suitable for the vast majority of use-cases; a PUBSUB client specifically for Redis’s PUBSUB functionality.
§Low-level
client::connect
returns a pair of Sink
and Stream
(see futures) which
both transport resp::RespValue
s between client and Redis, these work independently of one another
to allow pipelining. It is the responsibility of the caller to match responses to requests. It is also the
responsibility of the client to convert application data into instances of resp::RespValue
and
back (there are conversion traits available for common examples).
This is a very low-level API compared to most Redis clients, but is done so intentionally, for two reasons: 1) it is
the common demoniator between a functional Redis client (i.e. is able to support all types of requests, including those
that block and have streaming responses), and 2) it results in clean Sink
s and Stream
s which will be composable
with other Tokio-based libraries.
For most practical purposes this low-level interface will not be used, the only exception possibly being the
MONITOR
command.
§High-level
client::paired_connect
is used for most Redis commands (those for which one command
returns one response, it’s not suitable for PUBSUB, MONITOR
or other similar commands). It allows a Redis command to
be sent and a Future returned for each command.
Commands will be sent in the order that send
is called, regardless
of how the future is realised. This is to allow us to take advantage of Redis’s features by implicitly pipelining
commands where appropriate. One side-effect of this is that for many commands, e.g. SET
we don’t need to realise the
future at all, it can be assumed to be fire-and-forget; but, the final future of the final command does need to be
realised (at least) to ensure that the correct behaviour is observed.
§PUBSUB
PUBSUB in Redis works differently. A connection will subscribe to one or more topics, then receive all messages that
are published to that topic. As such the single-request/single-response model of
paired_connect
will not work. A specific
client::pubsub_connect
is provided for this purpose.
It returns a future which resolves to a PubsubConnection
, this provides a
subscribe
function that takes a topic as a parameter and
returns a future which, once the subscription is confirmed, resolves to a stream that contains all messages published
to that topic.
Modules§
- The client API itself.
- Error handling
- An implementation of the RESP protocol
Macros§
- Macro to create a RESP array, useful for preparing commands to send. Elements can be any type, or a mixture of types, that satisfy
Into<RespValue>
.